<div id="Branching-and-merging"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[cvs: Revisions#Sticky-tags  &lt; ]|</td>
<td valign="middle" align="left">|[[#Branches-motivation| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[cvs: Revisions#Revisions  &lt;&lt; ]|</td>
<td valign="middle" align="left">|[[cvs#Top| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Branching-and-merging-1"></div>
== Branching and merging ==
<div id="index-Branching"></div>
<div id="index-Merging"></div>
<div id="index-Copying-changes"></div>
<div id="index-Main-trunk-and-branches"></div>
<div id="index-Revision-tree_002c-making-branches"></div>
<div id="index-Branches_002c-copying-changes-between"></div>
<div id="index-Changes_002c-copying-between-branches"></div>
<div id="index-Modifications_002c-copying-between-branches"></div>

<p><small>CVS</small> allows you to isolate changes onto a separate
line of development, known as a <em>branch</em>.  When you
change files on a branch, those changes do not appear
on the main trunk or other branches.
</p>
<p>Later you can move changes from one branch to another
branch (or the main trunk) by <em>merging</em>.  Merging
involves first running <code>cvs update -j</code>, to merge
the changes into the working directory.
You can then commit that revision, and thus effectively
copy the changes onto another branch.
</p>
<pre class="menu-preformatted"><nowiki></nowiki>&bull;[[#Branches-motivation| Branches motivation]]::<nowiki>         What branches are good for
</nowiki>&bull;[[#Creating-a-branch| Creating a branch]]::<nowiki>           Creating a branch
</nowiki>&bull;[[#Accessing-branches| Accessing branches]]::<nowiki>          Checking out and updating branches
</nowiki>&bull;[[#Branches-and-revisions| Branches and revisions]]::<nowiki>      Branches are reflected in revision numbers
</nowiki>&bull;[[#Magic-branch-numbers| Magic branch numbers]]::<nowiki>        Magic branch numbers
</nowiki>&bull;[[#Merging-a-branch| Merging a branch]]::<nowiki>            Merging an entire branch
</nowiki>&bull;[[#Merging-more-than-once| Merging more than once]]::<nowiki>      Merging from a branch several times
</nowiki>&bull;[[#Merging-two-revisions| Merging two revisions]]::<nowiki>       Merging differences between two revisions
</nowiki>&bull;[[#Merging-adds-and-removals| Merging adds and removals]]::<nowiki>   What if files are added or removed?
</nowiki>&bull;[[#Merging-and-keywords| Merging and keywords]]::<nowiki>        Avoiding conflicts due to keyword substitution
</nowiki></pre>
<hr size="6">
<div id="Branches-motivation"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Branching-and-merging| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Creating-a-branch| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Branching-and-merging| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Branching-and-merging| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="What-branches-are-good-for"></div>
=== What branches are good for ===
<div id="index-Branches-motivation"></div>
<div id="index-What-branches-are-good-for"></div>
<div id="index-Motivation-for-branches"></div>

<p>Suppose that release 1.0 of tc has been made.  You are continuing to
develop tc, planning to create release 1.1 in a couple of months.  After a
while your customers start to complain about a fatal bug.  You check
out release 1.0 (see section [cvs: Revisions#Tags Tags&ndash;Symbolic revisions]) and find the bug
(which turns out to have a trivial fix).  However, the current revision
of the sources are in a state of flux and are not expected to be stable
for at least another month.  There is no way to make a
bugfix release based on the newest sources.
</p>
<p>The thing to do in a situation like this is to create a <em>branch</em> on
the revision trees for all the files that make up
release 1.0 of tc.  You can then make
modifications to the branch without disturbing the main trunk.  When the
modifications are finished you can elect to either incorporate them on
the main trunk, or leave them on the branch.
</p>
<hr size="6">
<div id="Creating-a-branch"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Branches-motivation| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Accessing-branches| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Branching-and-merging| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Branching-and-merging| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Creating-a-branch-1"></div>
=== Creating a branch ===
<div id="index-Creating-a-branch"></div>
<div id="index-Branch_002c-creating-a"></div>
<div id="index-tag-_0028subcommand_0029_002c-creating-a-branch-using"></div>
<div id="index-rtag-_0028subcommand_0029_002c-creating-a-branch-using"></div>

<p>You can create a branch with <code>tag -b</code>; for
example, assuming you&rsquo;re in a working copy:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs tag -b rel-1-0-patches
</nowiki></pre></td></tr></table>


<p>This splits off a branch based on the current revisions
in the working copy, assigning that branch the name
&lsquo;<samp>rel-1-0-patches</samp>&rsquo;.
</p>
<p>It is important to understand that branches get created
in the repository, not in the working copy.  Creating a
branch based on current revisions, as the above example
does, will <em>not</em> automatically switch the working
copy to be on the new branch.  For information on how
to do that, see [[#Accessing-branches|Accessing branches]].
</p>
<p>You can also create a branch without reference to any
working copy, by using <code>rtag</code>:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc
</nowiki></pre></td></tr></table>

<p>&lsquo;<samp>-r rel-1-0</samp>&rsquo; says that this branch should be
rooted at the revision that
corresponds to the tag &lsquo;<samp>rel-1-0</samp>&rsquo;.  It need not
be the most recent revision &ndash; it&rsquo;s often useful to
split a branch off an old revision (for example, when
fixing a bug in a past release otherwise known to be
stable).
</p>
<p>As with &lsquo;<samp>tag</samp>&rsquo;, the &lsquo;<samp>-b</samp>&rsquo; flag tells
<code>rtag</code> to create a branch (rather than just a
symbolic revision name).  Note that the numeric
revision number that matches &lsquo;<samp>rel-1-0</samp>&rsquo; will
probably be different from file to file.
</p>
<p>So, the full effect of the command is to create a new
branch &ndash; named &lsquo;<samp>rel-1-0-patches</samp>&rsquo; &ndash; in module
&lsquo;<samp>tc</samp>&rsquo;, rooted in the revision tree at the point tagged
by &lsquo;<samp>rel-1-0</samp>&rsquo;.
</p>
<hr size="6">
<div id="Accessing-branches"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Creating-a-branch| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Branches-and-revisions| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Branching-and-merging| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Branching-and-merging| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Accessing-branches-1"></div>
=== Accessing branches ===
<div id="index-Check-out-a-branch"></div>
<div id="index-Retrieve-a-branch"></div>
<div id="index-Access-a-branch"></div>
<div id="index-Identifying-a-branch"></div>
<div id="index-Branch_002c-check-out"></div>
<div id="index-Branch_002c-retrieving"></div>
<div id="index-Branch_002c-accessing"></div>
<div id="index-Branch_002c-identifying"></div>

<p>You can retrieve a branch in one of two ways: by
checking it out fresh from the repository, or by
switching an existing working copy over to the branch.
</p>
<p>To check out a branch from the repository, invoke
&lsquo;<samp>checkout</samp>&rsquo; with the &lsquo;<samp>-r</samp>&rsquo; flag, followed by
the tag name of the branch (see section [[#Creating-a-branch|Creating a branch]]):
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs checkout -r rel-1-0-patches tc
</nowiki></pre></td></tr></table>

<p>Or, if you already have a working copy, you can switch
it to a given branch with &lsquo;<samp>update -r</samp>&rsquo;:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs update -r rel-1-0-patches tc
</nowiki></pre></td></tr></table>

<p>or equivalently:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cd tc
$ cvs update -r rel-1-0-patches
</nowiki></pre></td></tr></table>

<p>It does not matter if the working copy was originally
on the main trunk or on some other branch &ndash; the above
command will switch it to the named branch.  And
similarly to a regular &lsquo;<samp>update</samp>&rsquo; command,
&lsquo;<samp>update -r</samp>&rsquo; merges any changes you have made,
notifying you of conflicts where they occur.
</p>
<p>Once you have a working copy tied to a particular
branch, it remains there until you tell it otherwise.
This means that changes checked in from the working
copy will add new revisions on that branch, while
leaving the main trunk and other branches unaffected.
</p>
<div id="index-Branches_002c-sticky"></div>
<p>To find out what branch a working copy is on, you can
use the &lsquo;<samp>status</samp>&rsquo; command.  In its output, look for
the field named &lsquo;<samp>Sticky tag</samp>&rsquo; (see section [cvs: Revisions#Sticky-tags Sticky tags])
&ndash; that&rsquo;s <small>CVS</small>&rsquo;s way of telling you the branch, if
any, of the current working files:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs status -v driver.c backend.c
===================================================================
File: driver.c          Status: Up-to-date

    Version:            1.7     Sat Dec  5 18:25:54 1992
    RCS Version:        1.7     /u/cvsroot/yoyodyne/tc/driver.c,v
    Sticky Tag:         rel-1-0-patches (branch: 1.7.2)
    Sticky Date:        (none)
    Sticky Options:     (none)

    Existing Tags:
        rel-1-0-patches             (branch: 1.7.2)
        rel-1-0                     (revision: 1.7)

===================================================================
File: backend.c         Status: Up-to-date

    Version:            1.4     Tue Dec  1 14:39:01 1992
    RCS Version:        1.4     /u/cvsroot/yoyodyne/tc/backend.c,v
    Sticky Tag:         rel-1-0-patches (branch: 1.4.2)
    Sticky Date:        (none)
    Sticky Options:     (none)

    Existing Tags:
        rel-1-0-patches             (branch: 1.4.2)
        rel-1-0                     (revision: 1.4)
        rel-0-4                     (revision: 1.4)

</nowiki></pre></td></tr></table>

<p>Don&rsquo;t be confused by the fact that the branch numbers
for each file are different (&lsquo;<samp>1.7.2</samp>&rsquo; and
&lsquo;<samp>1.4.2</samp>&rsquo; respectively).  The branch tag is the
same, &lsquo;<samp>rel-1-0-patches</samp>&rsquo;, and the files are
indeed on the same branch.  The numbers simply reflect
the point in each file&rsquo;s revision history at which the
branch was made.  In the above example, one can deduce
that &lsquo;<samp>driver.c</samp>&rsquo; had been through more changes than
&lsquo;<samp>backend.c</samp>&rsquo; before this branch was created.
</p>
<p>See [[#Branches-and-revisions|Branches and revisions]] for details about how
branch numbers are constructed.
</p>
<hr size="6">
<div id="Branches-and-revisions"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Accessing-branches| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Magic-branch-numbers| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Branching-and-merging| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Branching-and-merging| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Branches-and-revisions-1"></div>
=== Branches and revisions ===
<div id="index-Branch-number-1"></div>
<div id="index-Number_002c-branch-1"></div>
<div id="index-Revision-numbers-_0028branches_0029"></div>

<p>Ordinarily, a file&rsquo;s revision history is a linear
series of increments (see section [cvs: Revisions#Revision-numbers Revision numbers]):
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>       +-----+    +-----+    +-----+    +-----+    +-----+
       ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
       +-----+    +-----+    +-----+    +-----+    +-----+
</nowiki></pre></td></tr></table>

<p>However, <small>CVS</small> is not limited to linear development.  The
<em>revision tree</em> can be split into <em>branches</em>,
where each branch is a self-maintained line of
development.  Changes made on one branch can easily be
moved back to the main trunk.
</p>
<p>Each branch has a <em>branch number</em>, consisting of an
odd number of period-separated decimal integers.  The
branch number is created by appending an integer to the
revision number where the corresponding branch forked
off.  Having branch numbers allows more than one branch
to be forked off from a certain revision.
</p>
<p>All revisions on a branch have revision numbers formed
by appending an ordinal number to the branch number.
The following figure illustrates branching with an
example.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>                                                      +-------------+
                           Branch 1.2.2.3.2 -&gt;        ! 1.2.2.3.2.1 !
                                                    / +-------------+
                                                   /
                                                  /
                 +---------+    +---------+    +---------+
Branch 1.2.2 -&gt; _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
               / +---------+    +---------+    +---------+
              /
             /
+-----+    +-----+    +-----+    +-----+    +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !  &lt;- The main trunk
+-----+    +-----+    +-----+    +-----+    +-----+
                !
                !
                !   +---------+    +---------+    +---------+
Branch 1.2.4 -&gt; +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
                    +---------+    +---------+    +---------+

</nowiki></pre></td></tr></table>



<p>The exact details of how the branch number is
constructed is not something you normally need to be
concerned about, but here is how it works: When
<small>CVS</small> creates a branch number it picks the first
unused even integer, starting with 2.  So when you want
to create a branch from revision 6.4 it will be
numbered 6.4.2.  All branch numbers ending in a zero
(such as 6.4.0) are used internally by <small>CVS</small>
(see section [[#Magic-branch-numbers|Magic branch numbers]]).  The branch 1.1.1 has a
special meaning.  See section [cvs: Tracking third-party sources#Tracking-sources Tracking third-party sources].
</p>
<hr size="6">
<div id="Magic-branch-numbers"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Branches-and-revisions| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Merging-a-branch| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Branching-and-merging| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Branching-and-merging| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Magic-branch-numbers-1"></div>
=== Magic branch numbers ===


<p>This section describes a <small>CVS</small> feature called
<em>magic branches</em>.  For most purposes, you need not
worry about magic branches; <small>CVS</small> handles them for
you.  However, they are visible to you in certain
circumstances, so it may be useful to have some idea of
how it works.
</p>
<p>Externally, branch numbers consist of an odd number of
dot-separated decimal integers.  See section [cvs: Revisions#Revision-numbers Revision numbers].  That is not the whole truth, however.  For
efficiency reasons <small>CVS</small> sometimes inserts an extra 0
in the second rightmost position (1.2.4 becomes
1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so
on).
</p>
<p><small>CVS</small> does a pretty good job at hiding these so
called magic branches, but in a few places the hiding
is incomplete:
</p>
<ul>
<li>
The magic branch number appears in the output from
<code>cvs log</code>.

</li><li>
You cannot specify a symbolic branch name to <code>cvs
admin</code>.

</li></ul>

<p>You can use the <code>admin</code> command to reassign a
symbolic name to a branch the way <small>RCS</small> expects it
to be.  If <code>R4patches</code> is assigned to the branch
1.4.2 (magic branch number 1.4.0.2) in file
&lsquo;<tt>numbers.c</tt>&rsquo; you can do this:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs admin -NR4patches:1.4.2 numbers.c
</nowiki></pre></td></tr></table>

<p>It only works if at least one revision is already
committed on the branch.  Be very careful so that you
do not assign the tag to the wrong number.  (There is
no way to see how the tag was assigned yesterday).
</p>
<hr size="6">
<div id="Merging-a-branch"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Magic-branch-numbers| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Merging-more-than-once| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Branching-and-merging| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Branching-and-merging| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Merging-an-entire-branch"></div>
=== Merging an entire branch ===
<div id="index-Merging-a-branch"></div>
<div id="index-_002dj-_0028merging-branches_0029"></div>

<p>You can merge changes made on a branch into your working copy by giving
the &lsquo;<samp>-j <var>branchname</var></samp>&rsquo; flag to the <code>update</code> subcommand.  With one
&lsquo;<samp>-j <var>branchname</var></samp>&rsquo; option it merges the changes made between the
greatest common ancestor (GCA) of the branch and the destination revision (in
the simple case below the GCA is the point where the branch forked) and the
newest revision on that branch into your working copy.
</p>
<div id="index-Join"></div>
<p>The &lsquo;<samp>-j</samp>&rsquo; stands for &ldquo;join&rdquo;.
</p>
<div id="index-Branch-merge-example"></div>
<div id="index-Example_002c-branch-merge"></div>
<div id="index-Merge_002c-branch-example"></div>
<p>Consider this revision tree:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>+-----+    +-----+    +-----+    +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !      &lt;- The main trunk
+-----+    +-----+    +-----+    +-----+
                !
                !
                !   +---------+    +---------+
Branch R1fix -&gt; +---! 1.2.2.1 !----! 1.2.2.2 !
                    +---------+    +---------+
</nowiki></pre></td></tr></table>

<p>The branch 1.2.2 has been given the tag (symbolic name) &lsquo;<samp>R1fix</samp>&rsquo;.  The
following example assumes that the module &lsquo;<samp>mod</samp>&rsquo; contains only one
file, &lsquo;<tt>m.c</tt>&rsquo;.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs checkout mod               # <span class="roman">Retrieve the latest revision, 1.4</span>

$ cvs update -j R1fix m.c        # <span class="roman">Merge all changes made on the branch,</span>
                                 # <span class="roman">i.e. the changes between revision 1.2</span>
                                 # <span class="roman">and 1.2.2.2, into your working copy</span>
                                 # <span class="roman">of the file.</span>

$ cvs commit -m &quot;Included R1fix&quot; # <span class="roman">Create revision 1.5.</span>
</nowiki></pre></td></tr></table>

<p>A conflict can result from a merge operation.  If that
happens, you should resolve it before committing the
new revision.  See section [cvs: Multiple developers#Conflicts-example Conflicts example].
</p>
<p>If your source files contain keywords (see section [cvs: Keyword substitution#Keyword-substitution Keyword substitution]),
you might be getting more conflicts than strictly necessary.  See
[[#Merging-and-keywords|Merging and keywords]], for information on how to avoid this.
</p>
<p>The <code>checkout</code> command also supports the &lsquo;<samp>-j <var>branchname</var></samp>&rsquo; flag.  The
same effect as above could be achieved with this:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs checkout -j R1fix mod
$ cvs commit -m &quot;Included R1fix&quot;
</nowiki></pre></td></tr></table>

<p>It should be noted that <code>update -j <var>tagname</var></code> will also work but may
not produce the desired result.  See section [[#Merging-adds-and-removals|Merging can add or remove files]], for more.
</p>
<hr size="6">
<div id="Merging-more-than-once"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Merging-a-branch| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Merging-two-revisions| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Branching-and-merging| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Branching-and-merging| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Merging-from-a-branch-several-times"></div>
=== Merging from a branch several times ===

<p>Continuing our example, the revision tree now looks
like this:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>+-----+    +-----+    +-----+    +-----+    +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !   &lt;- The main trunk
+-----+    +-----+    +-----+    +-----+    +-----+
                !                           *
                !                          *
                !   +---------+    +---------+
Branch R1fix -&gt; +---! 1.2.2.1 !----! 1.2.2.2 !
                    +---------+    +---------+
</nowiki></pre></td></tr></table>

<p>where the starred line represents the merge from the
&lsquo;<samp>R1fix</samp>&rsquo; branch to the main trunk, as just
discussed.
</p>
<p>Now suppose that development continues on the
&lsquo;<samp>R1fix</samp>&rsquo; branch:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>+-----+    +-----+    +-----+    +-----+    +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !   &lt;- The main trunk
+-----+    +-----+    +-----+    +-----+    +-----+
                !                           *
                !                          *
                !   +---------+    +---------+    +---------+
Branch R1fix -&gt; +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
                    +---------+    +---------+    +---------+
</nowiki></pre></td></tr></table>

<p>and then you want to merge those new changes onto the
main trunk.  If you just use the <code>cvs update -j
R1fix m.c</code> command again, <small>CVS</small> will attempt to
merge again the changes which you have already merged,
which can have undesirable side effects.
</p>
<p>So instead you need to specify that you only want to
merge the changes on the branch which have not yet been
merged into the trunk.  To do that you specify two
&lsquo;<samp>-j</samp>&rsquo; options, and <small>CVS</small> merges the changes from
the first revision to the second revision.  For
example, in this case the simplest way would be
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>cvs update -j 1.2.2.2 -j R1fix m.c    # <span class="roman">Merge changes from 1.2.2.2 to the</span>
                                      # <span class="roman">head of the R1fix branch</span>
</nowiki></pre></td></tr></table>

<p>The problem with this is that you need to specify the
1.2.2.2 revision manually.  A slightly better approach
might be to use the date the last merge was done:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>cvs update -j R1fix:yesterday -j R1fix m.c
</nowiki></pre></td></tr></table>

<p>Better yet, tag the R1fix branch after every merge into
the trunk, and then use that tag for subsequent merges:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
</nowiki></pre></td></tr></table>

<hr size="6">
<div id="Merging-two-revisions"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Merging-more-than-once| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Merging-adds-and-removals| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Branching-and-merging| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Branching-and-merging| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Merging-differences-between-any-two-revisions"></div>
=== Merging differences between any two revisions ===
<div id="index-Merging-two-revisions"></div>
<div id="index-Revisions_002c-merging-differences-between"></div>
<div id="index-Differences_002c-merging"></div>

<p>With two &lsquo;<samp>-j <var>revision</var></samp>&rsquo; flags, the <code>update</code>
(and <code>checkout</code>) command can merge the differences
between any two revisions into your working file.
</p>
<div id="index-Undoing-a-change"></div>
<div id="index-Removing-a-change"></div>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs update -j 1.5 -j 1.3 backend.c
</nowiki></pre></td></tr></table>

<p>will undo all changes made between revision
1.3 and 1.5.  Note the order of the revisions!
</p>
<p>If you try to use this option when operating on
multiple files, remember that the numeric revisions will
probably be very different between the various files.
You almost always use symbolic
tags rather than revision numbers when operating on
multiple files.
</p>
<div id="index-Restoring-old-version-of-removed-file"></div>
<div id="index-Resurrecting-old-version-of-dead-file"></div>
<p>Specifying two &lsquo;<samp>-j</samp>&rsquo; options can also undo file
removals or additions.  For example, suppose you have
a file
named &lsquo;<tt>file1</tt>&rsquo; which existed as revision 1.1, and
you then removed it (thus adding a dead revision 1.2).
Now suppose you want to add it again, with the same
contents it had previously.  Here is how to do it:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs update -j 1.2 -j 1.1 file1
U file1
$ cvs commit -m test
Checking in file1;
/tmp/cvs-sanity/cvsroot/first-dir/file1,v  &lt;--  file1
new revision: 1.3; previous revision: 1.2
done
$
</nowiki></pre></td></tr></table>

<hr size="6">
<div id="Merging-adds-and-removals"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Merging-two-revisions| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Merging-and-keywords| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Branching-and-merging| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Branching-and-merging| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Merging-can-add-or-remove-files"></div>
=== Merging can add or remove files ===

<p>If the changes which you are merging involve removing
or adding some files, <code>update -j</code> will reflect
such additions or removals.
</p>
<p>For example:
</p><table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>cvs update -A
touch a b c
cvs add a b c ; cvs ci -m &quot;added&quot; a b c
cvs tag -b branchtag
cvs update -r branchtag
touch d ; cvs add d
rm a ; cvs rm a
cvs ci -m &quot;added d, removed a&quot;
cvs update -A
cvs update -jbranchtag
</nowiki></pre></td></tr></table>

<p>After these commands are executed and a &lsquo;<samp>cvs commit</samp>&rsquo; is done,
file &lsquo;<tt>a</tt>&rsquo; will be removed and file &lsquo;<tt>d</tt>&rsquo; added in the main branch.
</p>
<p>Note that using a single static tag (&lsquo;<samp>-j <var>tagname</var></samp>&rsquo;)
rather than a dynamic tag (&lsquo;<samp>-j <var>branchname</var></samp>&rsquo;) to merge
changes from a branch will usually not remove files which were removed on the
branch since <small>CVS</small> does not automatically add static tags to dead revisions.
The exception to this rule occurs when
a static tag has been attached to a dead revision manually.  Use the branch tag
to merge all changes from the branch or use two static tags as merge endpoints
to be sure that all intended changes are propagated in the merge.
</p>
<hr size="6">
<div id="Merging-and-keywords"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Merging-adds-and-removals| &lt; ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Branching-and-merging| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Branching-and-merging| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Merging-and-keywords-1"></div>
=== Merging and keywords ===
<div id="index-Merging_002c-and-keyword-substitution"></div>
<div id="index-Keyword-substitution_002c-and-merging"></div>
<div id="index-_002dj-_0028merging-branches_0029_002c-and-keyword-substitution"></div>
<div id="index-_002dkk_002c-to-avoid-conflicts-during-a-merge"></div>

<p>If you merge files containing keywords (see section [cvs: Keyword substitution#Keyword-substitution Keyword substitution]), you will normally get numerous
conflicts during the merge, because the keywords are
expanded differently in the revisions which you are
merging.
</p>
<p>Therefore, you will often want to specify the
&lsquo;<samp>-kk</samp>&rsquo; (see section [cvs: Keyword substitution#Substitution-modes Substitution modes]) switch to the
merge command line.  By substituting just the name of
the keyword, not the expanded value of that keyword,
this option ensures that the revisions which you are
merging will be the same as each other, and avoid
spurious conflicts.
</p>
<p>For example, suppose you have a file like this:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>       +---------+
      _! 1.1.2.1 !   &lt;-  br1
     / +---------+
    /
   /
+-----+    +-----+
! 1.1 !----! 1.2 !
+-----+    +-----+
</nowiki></pre></td></tr></table>

<p>and your working directory is currently on the trunk
(revision 1.2).  Then you might get the following
results from a merge:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cat file1
key $<i></i>Revision: 1.2 $
. . .
$ cvs update -j br1
U file1
RCS file: /cvsroot/first-dir/file1,v
retrieving revision 1.1
retrieving revision 1.1.2.1
Merging differences between 1.1 and 1.1.2.1 into file1
rcsmerge: warning: conflicts during merge
$ cat file1
&lt;&lt;&lt;&lt;&lt;&lt;&lt; file1
key $<i></i>Revision: 1.2 $
=======
key $<i></i>Revision: 1.1.2.1 $
&gt;&gt;&gt;&gt;&gt;&gt;&gt; 1.1.2.1
. . .
</nowiki></pre></td></tr></table>

<p>What happened was that the merge tried to merge the
differences between 1.1 and 1.1.2.1 into your working
directory.  So, since the keyword changed from
<code>Revision: 1.1</code> to <code>Revision: 1.1.2.1</code>,
<small>CVS</small> tried to merge that change into your working
directory, which conflicted with the fact that your
working directory had contained <code>Revision: 1.2</code>.
</p>
<p>Here is what happens if you had used &lsquo;<samp>-kk</samp>&rsquo;:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cat file1
key $<i></i>Revision: 1.2 $
. . .
$ cvs update -kk -j br1
U file1
RCS file: /cvsroot/first-dir/file1,v
retrieving revision 1.1
retrieving revision 1.1.2.1
Merging differences between 1.1 and 1.1.2.1 into file1
$ cat file1
key $<i></i>Revision$
. . .
</nowiki></pre></td></tr></table>

<p>What is going on here is that revision 1.1 and 1.1.2.1
both expand as plain <code>Revision</code>, and therefore
merging the changes between them into the working
directory need not change anything.  Therefore, there
is no conflict.
</p>
<p><strong>WARNING: In versions of <small>CVS</small> prior to 1.12.2, there was a
major problem with using &lsquo;<samp>-kk</samp>&rsquo; on merges.  Namely, &lsquo;<samp>-kk</samp>&rsquo;
overrode any default keyword expansion mode set in the archive file in
the repository.  This could, unfortunately for some users, cause data
corruption in binary files (with a default keyword expansion mode set
to &lsquo;<samp>-kb</samp>&rsquo;).  Therefore, when a repository contained binary files,
conflicts had to be dealt with manually rather than using &lsquo;<samp>-kk</samp>&rsquo; in
a merge command.</strong>
</p>
<p>In <small>CVS</small> version 1.12.2 and later, the keyword expansion mode
provided on the command line to any <small>CVS</small> command no longer
overrides the &lsquo;<samp>-kb</samp>&rsquo; keyword expansion mode setting for binary
files, though it will still override other default keyword expansion
modes.  You can now safely merge using &lsquo;<samp>-kk</samp>&rsquo; to avoid spurious conflicts
on lines containing RCS keywords, even when your repository contains
binary files.
</p>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Branching-and-merging| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[cvs: Recursive behavior#Recursive-behavior  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
This document was generated by <em>a tester</em> on <em>a sunny day</em> using [http://www.nongnu.org/texi2html/ <em>texi2html</em>].
